docs/development/Building in Mac OS X.md

   1 # Building in Mac OS X
   2
   3 Building in Mac OS X can be accomplished in just a few steps:
   4
   5 * Install general development tools (clang, make, git)
   6 * Install cmake
   7 * Checkout INAV sourcecode through git
   8 * Build the code
   9
  10 ## Install general development tools (clang, make, git)
  11
  12 Open up a terminal and run `make`. If it is installed already, you should see a message like this, which means that you
  13 already have the required development tools installed:
  14
  15 ```
  16 make: *** No targets specified and no makefile found.  Stop.
  17 ```
  18
  19 If it isn't installed yet, you might get a popup like this. If so, click the "install" button to install the commandline
  20 developer tools:
  21
  22 ![Prompt to install developer tools](assets/mac-prompt-tools-install.png)
  23
  24 If you just get an error like this instead of a helpful popup prompt:
  25
  26 ```
  27 -bash: make: command not found
  28 ```
  29
  30 Try running `xcode-select --install` instead to trigger the popup.
  31
  32 If that doesn't work, you'll need to install the XCode development environment [from the App Store][]. After
  33 installation, open up XCode and enter its preferences menu. Go to the "downloads" tab and install the
  34 "command line tools" package.
  35
  36 [from the App Store]: https://itunes.apple.com/us/app/xcode/id497799835
  37
  38 ## Install cmake
  39
  40 The easiest way to install cmake's command line executable is via
  41 [Homebrew](https://brew.sh) (a package manager for macOS). Go to their site
  42 and follow their installation instructions.
  43
  44 Once Homebrew is installed, type `brew install cmake` in a terminal to install
  45 cmake.
  46
  47 Alternatively, cmake binaries for macOS are available from
  48 [cmake.org](https://cmake.org/download/). If you prefer installing it this way,
  49 you'd have to manually add cmake's command line binary to your `$PATH`. Assuming
  50 `CMake.app` has been copied to `/Applications`, adding the following line to
  51 `~/.zshrc` would make the cmake command available.
  52
  53 ```sh
  54 export PATH=$PATH:/Applications/CMake.app/Contents/bin
  55 ```
  56
  57 ## Ruby
  58
  59 Ruby is installed by default on macOS.
  60
  61 ## Checkout INAV sourcecode through git
  62
  63 Enter your development directory and clone the [INAV repository][] using the "HTTPS clone URL" which is shown on
  64 the right side of the INAV GitHub page, like so:
  65
  66 ```
  67 git clone https://github.com/iNavFlight/inav
  68 ```
  69
  70 This will download the entire INAV repository for you into a new folder called "inav".
  71
  72 [INAV repository]: https://github.com/iNavFlight/inav.git
  73
  74 ## Build the code
  75
  76 Assuming you've just cloned the source code, you can switch your current
  77 directory to INAV's source try by typing:
  78
  79 ```sh
  80 cd inav
  81 ```
  82
  83 Inside the INAV directory, create a new directory to store the built files. This
  84 helps keeping everything nice and tidy, separating source code from artifacts. By
  85 convention this directory is usually called `build`, but any name would work. Enter
  86 the following command to create it and switch your working directory to it:
  87
  88 ```sh
  89 mkdir -p build && cd build
  90 ```
  91
  92 Now we need to configure the build by using the following command:
  93
  94 ```sh
  95 cmake ..
  96 ```
  97
  98 This will automatically download the required compiler for INAV, so it
  99 might take a few minutes. Once it's finished without errors, you can
 100 build the target that you want by typing `make target-name`. e.g.:
 101
 102 ```sh
 103 make -j8 MATEKF722 # Will build MATEKF722 target
 104 ```
 105
 106 A list of all the available targets can be displayed with:
 107
 108 ```sh
 109 make targets
 110 ```
 111
 112 Once the build completes, the correspondent `.hex` file will be found
 113 in current directory (e.g. `build`) and it will be named as
 114 `inav_x.y.z_TARGET.hex`. `x.y.z` corresponds to the INAV version number
 115 while `TARGET` will be the target name you've just built. e.g.
 116 `inav_2.6.0_MATEKF722.hex`. This is the file that can be flashed using
 117 INAV Configurator.
 118
 119 ## Updating to the latest source
 120
 121 If you want to erase your local changes and update to the latest version of the INAV source, enter your
 122 INAV directory and run these commands to first erase your local changes, fetch and merge the latest
 123 changes from the repository, then rebuild the firmware:
 124
 125 ```sh
 126 git reset --hard
 127 git pull
 128
 129 make target-name # e.g. make MATEKF722
 130 ```